package com.snda.relation.service.relation.biz.service;

import com.snda.relation.service.exception.ServiceInvocationException;
import com.snda.relation.service.opensocial.GetResponse;
import com.snda.relation.service.opensocial.UpdateResponse;
import com.snda.relation.service.relation.biz.domain.Group;
import com.snda.relation.service.relation.biz.domain.RelationFollow;

import com.snda.commons.servicegate.annotations.Endpoint;
import com.snda.commons.servicegate.annotations.Param;
import com.snda.commons.servicegate.annotations.Service;
import com.snda.commons.servicegate.validation.Number;
import com.snda.commons.servicegate.validation.Text;

/**
 * provide service for group including add a new group for a sdid, change the
 * information of a particular group, delete a particular group to get all the
 * group of a person(sdid).
 * 
 * @author yangjiandong
 * @since 2010-2-25
 * @file GroupService.java
 */
@Service("GroupService")
public interface GroupService {

	/**
	 * get a group object according to the groupid
	 * 
	 * @param groupId
	 * @return group
	 */
	@Endpoint(alias = "getGroup")
	public GetResponse<Group> listGroup(@Param("groupId") Long groupId,
			@Param("sdid") @Number(min=1)Long sdid);

	/**
	 * list all the people in a specific group
	 * 
	 * @param sdid
	 *            sdid and groupId should match each other
	 * @param groupId
	 * @param startIndex
	 * @param count
	 * @return the relationFollow list
	 * @throws ServiceInvocationException
	 */
	@Endpoint(alias = "getPeopleFromGroup")
	public GetResponse<RelationFollow> listPeopleFromGroup(
			@Param("sdid") @Number(min=1)Long sdid,
			@Param("groupId") Long groupId,
			@Param(value = "startIndex", defaultValue = "0", optional = true) Integer startIndex,
			@Param(value = "count", defaultValue = "0", optional = true) Integer count)
			throws ServiceInvocationException;

	/**
	 * get one person's grouplist,
	 * 
	 * @param sdid
	 * @return the list of groups the sdid owns
	 */
	@Endpoint(alias = "getPersonGroups")
	public GetResponse<Group> listPersonGroups(@Param("sdid") @Number(min=1)Long sdid)
			throws ServiceInvocationException;

	/**
	 * gernerating a group object
	 * 
	 * @param sdid
	 * @param groupName
	 * @return
	 * @throws ServiceInvocationException
	 *             when the value in the input group was not valid
	 */
	@Endpoint(alias = "addGroup")
	public UpdateResponse addGroup(@Param("sdid") @Number(min=1)Long sdid,
			@Param("appId") Long appId,
			@Param("groupName") @Text(maxLength = 20) String groupName)
			throws ServiceInvocationException;

	/**
	 * modify a exsiting group, name for example
	 * 
	 * @param group
	 * @param name
	 * @throws InvalidValueException
	 */
	@Endpoint(alias = "updateGroupName")
	public UpdateResponse modifyGroupName(@Param("groupId") Long groupId,
			@Param("sdid") @Number(min=1)Long sdid, @Param("groupName") String name)
			throws ServiceInvocationException;

	/**
	 * change the delete_tag of the group object to 1
	 * 
	 * @param gourpId
	 * @throws InvalidOperationException
	 *             when the group do not exist
	 */
	@Endpoint(alias = "deleteGroup")
	public UpdateResponse deleteGroup(@Param("groupId") Long groupId,
			@Param("sdid") @Number(min=1)Long sdid) throws ServiceInvocationException;

}
